.TH E1432_INSTALL 3 E1432
.SH NAME
e1432_install \- Install firmware into E1432 RAM
.IX e1432_install(3) 3
.SH SYNOPSIS
.cS
SHORTSIZ16 e1432_install(SHORTSIZ16 modCount, SHORTSIZ16 *logAddrList,
                         LONGSIZ32 flags, const void *path);
.cE
.SH DESCRIPTION
\fIe1432_install\fR installs firmware into E1432 RAM.  This must be
done after powerup or a hard reset.  Until this is done, the module is
unable to run a measurement or set or query parameter values.

\fImodCount\fR specifies how many different modules to install
firmware into.  The installation is done in parallel as much as
possible, so it is faster to call \fIe1432_install\fR and give it
several modules, rather than call \fIe1432_install\fR once for each
module.

\fIlogAddrList\fR is an array of VXI logical addresses.  This array
must be as long as \fImodCount\fR.  Firmware will be installed in each
E1432 module specified by this array.

\fIflags\fR is used to modify the installation process.  This value is
a bit field, with each bit signifying something different.  Normally,
\fIflags\fR should be specified as zero.  Values that are understood
are:

.IP \fBE1432_INSTALL_FASTEST\fR 28
This performs no handshaking while downloading the firmware.  \fIThis
fails except when the E1406 command module is being used\fR.

.IP \fBE1432_INSTALL_FASTER\fR 28
This downloads the first 4K block of firmware with handshaking, and
then uses no handshaking for the rest of the firmware.

.IP \fBE1432_INSTALL_FAST\fR 28
This is similar to \fBE1432_INSTALL_FASTER\fR, but it uses a slower
transfer method for non-handshaked transfers.

.IP \fBE1432_INSTALL_FROM_MEM\fR 28
Normally, \fIe1432_install\fR installs data from a file into the E1432
module.  If this bit is set, then instead \fIe1432_install\fR installs
data from a passed-in memory buffer specified by the \fIpath\fR
parameter.  See the "DOWNLOADING FROM A BUFFER" section below.

.IP \fBE1432_INSTALL_SYSCALLS\fR 28
This specifies that the \fIe1432mon\fR program is already running, and
the installed firmware should wait for the monitor to acknowledge each
debug print (and all other system calls).
.PP

None of the \fBFAST\fR flags above will work over a fast interface,
such as MXI or embedded V/743.

\fIpath\fR specifies the name of a file that contains the firmware to
download (except when \fBE1432_INSTALL_FROM_MEM\fR is set in the
\fIflags\fR parameter; see section "DOWNLOADING FROM A BUFFER" below).
Normally, this path should be set to \fC/opt/e1432/lib/sema.bin\fR.
This binary file is an exact image of the firmware that will execute
in the E1432 substrate 96002.
.SH "DOWNLOADING FROM A BUFFER"
Normally, \fIe1432_install\fR opens a file and downloads the contents
of the file to the E1432.  This is generally the easiest and most
efficient way to perform the download.  However, in special
circumstances (for example, when controlling an E1432 from an E1485),
it may be inconvenient to use a file.  To allow for this possibility,
the \fBE1432_INSTALL_FROM_MEM\fR bit in the \fIflags\fR parameter may
be used.  This bit indicates that a file will not be used for
downloading, and that the \fIpath\fR parameter is not a filename but
is instead a pointer to a structure of type
\fIe1432_install_from_mem\fR.  This structure has two fields: an
\fInbyte\fR field which specifies the number of bytes to install, and
a \fIdata\fR field which is a pointer to the actual data.

It is up to the application to set these two fields in the structure
pointed to by \fIpath\fR.  In the case of an E1485 program, the
contents of \fC/opt/e1432/lib/sema.bin\fR could be converted to ASCII,
embedded into the source code of the E1485 program, and \fIdata\fR
could be set to point to this embedded array.  Note that this would
make the E1485 program quite large.
.SH "IS DOWNLOADING NECESSARY?"
The process of downloading code into the E1432 module usually takes
more than five seconds.  Since it is so slow, an application
programmer generally wants to download code only when absolutely
necessary.  The best way to tell if the download is necessary is to
use the \fIe1432_get_hwconfig\fR function.  If
\fIe1432_get_hwconfig\fR returns an error, then downloading is
necessary.  If \fIe1432_get_hwconfig\fR is successful, then
downloading is generally not necessary.  The structure returned by a
successful call to \fIe1432_get_hwconfig\fR contains a field that
specifies the firmware revision of the code running in the E1432
module.

Here is a typical code fragment to deal with downloading, which will
download code into the E1432 only if needed:

.cS
    struct e1432_hwconfig hwconfig;
    SHORTSIZ16 laddr[E1432_MOD_MAX];
    SHORTSIZ16 nmod;

    nmod = 1;
    laddr[0] = 8;

    if (e1432_print_errors(0) < 0)
        return -1;
    status = e1432_get_hwconfig(nmod, laddr, hwconfig);
    if (e1432_print_errors(1) < 0)
        return -1;
    if (status < 0)
        if (e1432_install(nmod, laddr, 0, "/opt/e1432/lib/sema.bin") < 0)
            return -1;
.cE
.SH "RESET VALUE"
Not applicable.
.SH "RETURN VALUE"
Return 0 if successful, a (negative) error number otherwise.
.SH "SEE ALSO"
.na
e1432_assign_channel_numbers, e1432_get_hwconfig, e1432_init_io_driver
.ad
